<html><head><title>Simple Sequencing Engine reference</title>
<link rel=stylesheet Type=text/css href='../../../../doc/bmxstyle.css'>
</head><body>
<table width=100% cellspacing=0><tr align=center><td class=small>&nbsp;</td>
<td class=small width=1%><b>jmd.Sequence:</b></td>
<td class=small width=1%><a href=#functions class=small>Functions</a></td>
<td class=small width=1%><a href=#types class=small>Types</a></td>
<td class=small width=1%><a href=#modinfo class=small>Modinfo</a></td>
<td class=small width=1%><a href='../../../../mod/jmd.mod/sequence.mod/sequence.bmx' class=small>Source</a></td>
<td class=small>&nbsp;</td></tr></table>
<h1>Simple Sequencing Engine</h1>
This module provides a simple sequencing engine implementation. Each sequence is
built by any number of "steps" which can be handled in the order they were created.
Each step has convenience methods to assign/track integer step identifiers, store and retrieve a data object,
expire steps as well as track/set initialization of each sequence step. Steps operate on a simple
FIFO stack, and the functions and methods provided primarily work on the currently active step
(which is on top of the stack).
<h2><a name=functions></a>Functions Summary</h2><table class=doc width=100%>
<tr><td class=docleft width=1%><a href=#CreateSequence>CreateSequence</a></td><td class=docright>
Create a new sequence.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceAdd>SequenceAdd</a></td><td class=docright>
Add a new step to a sequence.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceAutoExpire>SequenceAutoExpire</a></td><td class=docright>
Auto-expire a sequence step.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceClear>SequenceClear</a></td><td class=docright>
Clear all steps from the current sequence.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceData>SequenceData</a></td><td class=docright>
Get the data object associated with the current sequence step.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceDoNext>SequenceDoNext</a></td><td class=docright>
Advance to the next step of the sequence.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceExpire>SequenceExpire</a></td><td class=docright>
Check if a sequence step has expired.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceGet>SequenceGet</a></td><td class=docright>
Get the current sequence step.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceInit>SequenceInit</a></td><td class=docright>
Sequence step initialization.
</td></tr>
<tr><td class=docleft width=1%><a href=#SequenceReInit>SequenceReInit</a></td><td class=docright>
Reinitialize a sequence step.
</td></tr>
</table>
<h2><a name=types></a>Types Summary</h2><table class=doc width=100%>
<tr><td class=docleft width=1%><a href=#TSequence>TSequence</a></td><td class=docright>
TSequence Type.
</td></tr>
<tr><td class=docleft width=1%><a href=#TSequenceStep>TSequenceStep</a></td><td class=docright>
TSequenceStep Type.
</td></tr>
</table>
<h2
 id=functionsdet>Functions
</h2>
<table class=doc width=100% cellspacing=3 id=CreateSequence>
<tr><td class=doctop colspan=2>Function CreateSequence:TSequence()</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>A <a href=#TSequence>TSequence</a> object.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Create a new sequence.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Creates a new <a href=#TSequence>TSequence</a> object.
Alternatively you can use the <b>TSequence.Create</b>() method.</td></tr>
<tr><td class=docleft width=1%><a href=CreateSequence.bmx class=small>Example</a></td><td class=docright><pre>'Sequencing example
'This is a simple example of a familiar "arcade" sequence of showing an intro screen for 10
'seconds, which then automatically transitions to the game's title screen. The title screen will
'stay on the screen for 30 seconds, waiting for user input to either quit or start the game.
'If no user input is given, then it will repeat showing the intro screen for 10 seconds, followed
'by the title screen for 30 seconds until user input is given.
'Once the user chooses to start the game (space bar), the game part of the sequence is entered.
'If the game step of the sequence is exited, then execution will return to the title screen - but
'this time, it will return the high score, and it will remain at the title screen indefinitely until user input is given. (I.e. the
'game is no longer in an "auto-advertise" mode as the user has obviously seen these before running the game.)
'This simple example is to show the utility of this sequencing engine, as well as show how easy it is to use!

SuperStrict
Import jmd.sequence

'Consts
Const STEP_INTRO:Int = 0
Const STEP_TITLE:Int = 1
Const STEP_RUN:Int= 3
Const STEP_EXIT:Int = 1000 'no need for any specific order!

'Create a new sequence
Local SEQ:TSequence = CreateSequence() 'alternatively, you can use TSequence.Create()

'Add our first 2 steps
'You can add as many sequence steps as you would like - here we are only adding 2.
'Note that you could also use the SequenceAdd() function instead...
SEQ.Add(STEP_INTRO,10*1000) '10 seconds
SEQ.Add(STEP_TITLE,30*1000) '30 seconds





Graphics 640,480
While Not KeyDown(KEY_ESCAPE)
	Cls
	
	
	'You can use a Select statement to get the current sequence step.
	'Then you can add your code for each different sequence step! Only the code
	'for the current step gets executed.
	Select SEQ.Get() 'alternative: SequenceGet(SEQ)
	Case STEP_INTRO
		If Not SEQ.Init() 'alternative: SequenceInit(SEQ)
			Print "(Intro Screen) Initialization only happens once!"
		EndIf
		
		DrawText "Intro Screen!",10,10
		DrawText "This is a good place to show your logo after running the application",10,30
		DrawText "No input is processed this step, so wait 10 seconds for it to autoexpire!",10,50
		
		SEQ.AutoExpire() 	'automatically expires step, and moves to the next
							'alternative: SequenceAutoExpire(SEQ)
	Case STEP_TITLE
		If Not SEQ.Init()
			Print "(Title Screen) Initialization only happens once!"
			FlushKeys() 'Since the RUN step also uses the Q key to exit,
						'we will flush this so it doesn't also exit this step
		EndIf
		
		DrawText "Title Screen",10,10
		DrawText "Put a title screen here with choices to start your game, etc.",10,30
		If SEQ.Data() 'Alternatively use SequenceData(SEQ)
			DrawText "Good Job! " + String(SEQ.Data()),10,50 'Since the data is an object, you must cast its type back to a string!
		Else
			DrawText "If no input is given after 30 seconds, we will advertise ourselves",10,50
			DrawText "by showing the title screen again for 10 seconds then coming back here.",10,70
		EndIf
		DrawText "Press the space bar to begin the game, or Q to quit.",10,110
		
		'Run the application if the space key is pressed!
		If KeyHit(KEY_SPACE)
			SEQ.Add(STEP_RUN,0)
			SEQ.DoNext() 'alternative: SequenceDoNext(SEQ)
		EndIf
		'Exit application if the "q" key is pressed
		If KeyHit(KEY_Q) 
			SEQ.Add(STEP_EXIT)
			SEQ.DoNext()
		EndIf
		
		'If this step is expired, lets restart the Intro/Title screen steps
		'Note that after the RUN step has executed, this step is created with
		'no expiration time, so this step will remain infinitely until the user
		'either runs the game again, or choses to quit.
		If SEQ.Expire() 'alternative: SequenceExpire(SEQ)
			SEQ.Add(STEP_INTRO,10*1000)
			SEQ.Add(STEP_TITLE,30*1000)
			SEQ.DoNext() 'alternative: SequenceDoNext(SEQ)
		EndIf
	Case STEP_RUN
		If Not SEQ.Init()
			Print "(Main Game Screen) Initialization only happens once!"
		EndIf

		DrawText "Welcome to my game!",10,10
		DrawText "This is where you would do your main game logic, for example.",10,30
		DrawText "Press Q to quit",10,50
		
		'Lets process the Exit condition!
		If KeyHit(KEY_Q)
			SEQ.Add(STEP_TITLE,0,"High Score: 5000") 'Don't autoexpire this time, and pass some data too!
			SEQ.DoNext()
		EndIf
	Case STEP_EXIT
		If Not SEQ.Init()
			Print "Initialization... Do stuff here..."
		EndIf
		Print "Exiting...Do cleanup code here..."
		End
		
	Default
		Print "Unknown sequence step! Skipping..."
		SEQ.DoNext()
	End Select
	
	
	
	Flip
Wend</pre></td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceAdd>
<tr><td class=doctop colspan=2>Function SequenceAdd(seq:TSequence,stepNum:Int,stepDur:Int,stepData:Object=Null)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>nothing.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Add a new step to a sequence.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Adds a new step to a sequence. It is usually advantageous to create constants for the
<b>stepNum</b> parameter to make code easier to read.
<a href=#SequenceExpire>SequenceExpire</a>() and <a href=#SequenceAutoExpire>SequenceAutoExpire</a>() can be used to see if this step is expired.
<a href=#SequenceDoNext>SequenceDoNext</a>() can be used to advance to the next step in the sequence.
<b>stepData</b> parameter is used to associate any data you wish with this step of the sequence.
It can be retrieved later with <a href=#SequenceData>SequenceData</a>(). Defaults to <a href=#Null>Null</a>.
Alternatively you can use the <b>TSequence.Add</b>() method.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceAutoExpire>
<tr><td class=doctop colspan=2>Function SequenceAutoExpire(seq:TSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>nothing.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Auto-expire a sequence step.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>This is a convience function which does nothing more than call <a href=#SequenceExpire>SequenceExpire</a>(), and then
call <a href=#SequenceDoNext>SequenceDoNext</a>() if <a href=#SequenceExpire>SequenceExpire</a>() returns true.
Alternatively you can use the <b>TSequence.AutoExpire</b>() method
<p>
note: Sequence steps created with 0 <b>stepDur</b> with <a href=#SequenceAdd>SequenceAdd</a>() are considered infinite, and will
not expire!</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceClear>
<tr><td class=doctop colspan=2>Function SequenceClear(seq:TSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>nothing.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Clear all steps from the current sequence.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Use to clear all steps from a sequence so you can start fresh.
Alternatively you can use the <b>TSequence.Clear</b>() method.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceData>
<tr><td class=doctop colspan=2>Function SequenceData:Object(seq:TSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>any object originally passed to <b>stepData</b> with <a href=#SequenceAdd>SequenceAdd</a>()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Get the data object associated with the current sequence step.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>There are often times where you will need to associate some data with each sequence step.
For example, you may want to store a message to display with each sequence step:
<pre>
SEQ.Add(STEP_INTRO,0,"We are in the intro screen!")
</pre>
<p>
which could later be retrieved like:
<p>
<pre>
print String(SEQ.Data())
</pre>
<p>
Alternatively you can use the <b>TSequence.Data</b>() method
<p>
note: Also note that more complex data objects can be stored/retrieved such as <a href=#TList>TList</a> and <a href=#TMap>TMap</a> objects,
allowing you to associate a virtually unlimited amount of data with each step of the sequence.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceDoNext>
<tr><td class=doctop colspan=2>Function SequenceDoNext(seq:TSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>nothing.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Advance to the next step of the sequence.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Effectively pops the current step off of the stack so that the next sequence in line
will be at the top of the stack. This is the command to use to move from one step of a sequence
to the next.
Alternatively you can use the <b>TSequence.DoNext</b>() method.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceExpire>
<tr><td class=doctop colspan=2>Function SequenceExpire:Int(seq:TSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright><b>True</b> or <b>False</b>.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Check if a sequence step has expired.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Use this to check if a sequence is expired. Use in combination with <a href=#SequenceDoNext>SequenceDoNext</a>() to
move from step to step in the sequence.
Alternatively you can use the <b>TSequence.Expire</b>() method
<p>
note: Sequence steps created with 0 <b>stepDur</b> with <a href=#SequenceAdd>SequenceAdd</a>() are considered infinite, and will
not expire!</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceGet>
<tr><td class=doctop colspan=2>Function SequenceGet:Int(seq:TSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>A <b>stepNum</b> identifier originally set with <a href=#SequenceAdd>SequenceAdd</a>()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Get the current sequence step.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>Use this in a Select statement or If statment to see what step the sequence is currently on.
Alternatively you can use the <b>TSequence.Get</b>() method.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceInit>
<tr><td class=doctop colspan=2>Function SequenceInit:Int(seq:TSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright><b>True</b> or <b>False</b>.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Sequence step initialization.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>When a sequence step is first created (using <a href=#SequenceAdd>SequenceAdd</a>()), its initialization state
is set to false.  When this function is called for the first time, it sets its internal initialization
state to true, and returns false. This allows the code wrapped in a conditional expression to be
executed the first time it is run only. This lets you cleanly initialize anything you need to
when a sequence step first starts.
note: See <a href=#SequenceReInit>SequenceReInit</a>() if you would like to reset the internal initialization state back to false.
This allows <a href=#SequenceInit>SequenceInit</a>() to return false once again so that your initialization code can be
re-run.
Alternatively you can use the <b>TSequence.Init</b>() method.</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=SequenceReInit>
<tr><td class=doctop colspan=2>Function SequenceReInit(seq:TSequence)</td></tr>
<tr><td class=docleft width=1%>Returns</td><td class=docright>nothing.</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>Reinitialize a sequence step.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>When a sequence step is first created (using <a href=#SequenceAdd>SequenceAdd</a>()), its initialization state
is set to false.  When this <a href=#SequenceInit>SequenceInit</a>() is called for the first time, it sets its internal initialization
state to true, and returns false. This allows the code wrapped in a conditional expression to be
executed the first time it is run only. This lets you cleanly initialize anything you need to
when a sequence step first starts.
Alternatively you can use the <b>TSequence.ReInit</b>() method.</td></tr>
</table>
<br>
<h2
 id=typesdet>Types
</h2>
<table class=doc width=100% cellspacing=3 id=TSequence>
<tr><td class=doctop colspan=2>Type TSequence</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>TSequence Type.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>This is the main type you will be dealing with.</td></tr>
</table>
<table class=doc width=90% align=center><tr ><th class=doctop colspan=2 align=left><a name=TSequence_methods></a>Methods Summary</th></tr>
<tr><td class=docleft width=1%><a href=#Add>Add</a></td><td class=docright>
alternative for <a href=#SequenceAdd>SequenceAdd</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#AutoExpire>AutoExpire</a></td><td class=docright>
alternative for <a href=#SequenceAutoExpire>SequenceAutoExpire</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Clear>Clear</a></td><td class=docright>
alternative for <a href=#SequenceClear>SequenceClear</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Count>Count</a></td><td class=docright>
alternative for <a href=#SequenceCount>SequenceCount</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Data>Data</a></td><td class=docright>
alternative for <a href=#SequenceData>SequenceData</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Expire>Expire</a></td><td class=docright>
alternative for <a href=#SequenceExpire>SequenceExpire</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Get>Get</a></td><td class=docright>
alternative for <a href=#SequenceGet>SequenceGet</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#Init>Init</a></td><td class=docright>
alternative for <a href=#SequenceInit>SequenceInit</a>()
</td></tr>
<tr><td class=docleft width=1%><a href=#ReInit>ReInit</a></td><td class=docright>
alternative for <a href=#SequenceReInit>SequenceReInit</a>()
</td></tr>
</table>
<table class=doc width=90% align=center><tr ><th class=doctop colspan=2 align=left><a name=TSequence_functions></a>Functions Summary</th></tr>
<tr><td class=docleft width=1%><a href=#Create>Create</a></td><td class=docright>
alternative for <a href=#CreateSequence>CreateSequence</a>()
</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Add>
<tr><td class=doctop colspan=2>Method Add(stepNum:Int,thisDuration:Int=0,data:Object=Null)</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceAdd>SequenceAdd</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=AutoExpire>
<tr><td class=doctop colspan=2>Method AutoExpire()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceAutoExpire>SequenceAutoExpire</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Clear>
<tr><td class=doctop colspan=2>Method Clear()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceClear>SequenceClear</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Count>
<tr><td class=doctop colspan=2>Method Count:Int()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceCount>SequenceCount</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Data>
<tr><td class=doctop colspan=2>Method Data:Object()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceData>SequenceData</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Expire>
<tr><td class=doctop colspan=2>Method Expire:Int()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceExpire>SequenceExpire</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Get>
<tr><td class=doctop colspan=2>Method Get:Int()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceGet>SequenceGet</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Init>
<tr><td class=doctop colspan=2>Method Init:Int()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceInit>SequenceInit</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=ReInit>
<tr><td class=doctop colspan=2>Method ReInit()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#SequenceReInit>SequenceReInit</a>()</td></tr>
</table>
<table class=doc width=100% cellspacing=3 id=Create>
<tr><td class=doctop colspan=2>Function Create:TSequence()</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>alternative for <a href=#CreateSequence>CreateSequence</a>()</td></tr>
</table>
<br>
<table class=doc width=100% cellspacing=3 id=TSequenceStep>
<tr><td class=doctop colspan=2>Type TSequenceStep</td></tr>
<tr><td class=docleft width=1%>Description</td><td class=docright>TSequenceStep Type.</td></tr>
<tr><td class=docleft width=1%>Information</td><td class=docright>This type is used behind the scenes by the <a href=#TSequence>TSequence</a> type to store information about
each step in the sequence.  You should never have to deal with this type directly.</td></tr>
</table>
<br>
<h2 id=modinfo>Module Information</h2>
<table width=100%>
<tr><th width=1%>Version</th><td>1.0</td></tr>
<tr><th width=1%>Author</th><td>Jonathan Decker</td></tr>
<tr><th width=1%>License</th><td>GNU GPL v3</td></tr>
<tr><th width=1%>SVN</th><td>http://blitzmax-sequence-module.googlecode.com/svn/trunk/</td></tr>
</body></html>
